/* ===================

AX2E (AXESCON XACML 2.0 Engine) is the Java authorization engine, which implements OASIS XACML 2.0 standard.
Copyright (C) 2007 AXESCON LLC

This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA


Contact: AXESCON LLC - info{at}axescon.com

 =================== */
package axescon.xacml.api;

import axescon.xacml.model.ctx.XacmlCtx;
import axescon.xacml.model.policy.AttributeValue;
import axescon.xacml.model.policy.Expression;

/**
 * @author argyn
 * Date: Sep 28, 2005
 *         Responsibilities: represents a factory, which can build functions.
 * @see Fn
 */
public interface FnFactory {

    /**
     * utility method, which can execute given function by name
     * @param fnName fn name, aka urn
     * @param args array of Expressions, arguments of function
     * @param ch context handler
     * @param req request
     * @param ee Expression Evaluator
     * @return Liquid result
     * @throws XacmlException
     * @throws ExpressionEvalIndeterminateException
     */
    Liquid exec(String fnName, Expression[] args, CtxHandler ch, XacmlCtx req, ExpressionEvaluator ee) throws
            XacmlException, ExpressionEvalIndeterminateException;


    /**
     * utility method, which can execute match functions
     * @see MatchFn
     *
     * @param fnName function name, or urn
     * @param arg0 argument 0
     * @param arg1 argument 1
     * @return true, if arguments match
     *
     * @throws ExpressionEvalIndeterminateException
     */
    boolean match(String fnName, AttributeValue arg0, AttributeValue arg1) throws
            ExpressionEvalIndeterminateException;

    /**
     * get function by name
     * @param fnName       function name, or urn
     * @return function object
     *
     * @throws ExpressionEvalIndeterminateException
     */
    Fn getFn(String fnName) throws ExpressionEvalIndeterminateException;

    /**
     * get match function by name
     * @param fnName       function name, or urn
     * @return match function object
     * @throws UnsupportedFunctionException
     * @see MatchFn
     */
    MatchFn getMatchFn(String fnName) throws UnsupportedFunctionException;

    /**
     * validates factory configuration.
     * @throws XacmlException
     */
    void validate() throws XacmlException;

    /**
     * adds a function to factory. this method can be used to add custom functions
     * to factory.
     * @param urn urn of new function
     * @param fn function instance
     */
    void addFn(String urn, Fn fn);


}
